CU Amiga Super CD-ROM 27

home *** CD-ROM | disk | FTP | other *** search

/ CU Amiga Super CD-ROM 27 / CU Amiga Magazine's Super CD-ROM 27 (1998)(EMAP Images)(GB)[!][issue 1998-10].iso / CUCD / Programming / Mesa / README.AMIGA < prev

Wrap

Text File | 1998-08-02 | 11.6 KB | 338 lines

AmigaMesaRTL 1.0 A run-time library of Mesa 2.6 by Jarno van der Linden jarno@kcbbs.gen.nz Mesa 2.6 is Copyright (C) 1995-1998 Brian Paul INTRODUCTION ============ Once upon a time there was an Amiga port of Mesa by Stefan Zivkovic. However, just as this port became interesting, Stefan could no longer support it. Then came CyberGL. A run-time library, which ran reasonably comfortably even on lower-end machines with AGA. Unfortunately, it only implemented a subset of OpenGL. Furthermore, the output even on a 256 colour AGA screen was far from impressive. At present, development seems to have stalled (possibly pending the release of the CV-PPC and BVision cards). Back to Mesa, through H&P we've seen the release of StormMesa. Unfortunately this too comes in the form of a link library. So I set out to create my own driver with the following objectives: - Based on the latest release of Mesa - Should come in the form of a run-time library - Reasonable speed on an 50MHz '030/'881 system - Good quality output on AGA With AmigaMesaRTL, I think I have achieved these goals. Of course, don't expect miracles. Framerates are still better counted in seconds-per-frame rather than frames-per-second on my machine (A1200, Blizzard1230IV, 50MHz '030/'881, 32MB fast). But it is still faster than CyberGL and the output is a significantly better. THEORY OF OPERATION =================== The driver (amigamesertl.c) does all reading from and writing to a simple memory buffer. This buffer is made up out of single bytes in the case of colour index mode, and 4 bytes in the case RGB or RGBA mode. When glFlush() is called, the buffer is written to the window using a quantization library. In index mode, the default quantizer calls WritePixelArray8(). In RGB mode, the buffer is first passed to a colour quantization algorithm. The resulting palette is loaded with LoadRGB32(), and the quantized buffer is written to the window with WritePixelArray8(). The quantizer is a slightly modified version of DL1 from a package by Dennis Lee (denlee@ecf.utoronto.ca). I've included the original documentation in the amiga/quantizers/dl1 directory. Because of the various buffers involved, AmigaMesaRTL does use a fair bit of memory. But the output is about as good as it can get in 256 colours, and as all the drawing is done off-screen most of the AGA speed bottleneck is avoided. COMPILING THE LIBRARY ===================== The AmigaMesaRTL distribution only contains the changed and new files of Mesa. You will need the Mesa 2.6 distribution. Once you have obtained the Mesa 2.6 distribution and unpacked it to somewhere, copy the amiga directory of AmigaMesaRTL to the Mesa directory. Go to the amiga/src directory, change the SCOPTIONS file to suit your system (mainly the MATH and CPU settings), and run SMake. Sit back, relax, enjoy life. This is going to take a while. Note that there are still a few references to __XCEXIT(). Just ignore it and let the linker replace it with __stub(). Once this is done, you should end up with a file called mesa.library in the amiga/library directory. Next, go to the amiga/lib directory, edit the SCOPTIONS file if you want to, run SMake. Out should come Mesa.LIB. Finally, compile a quantizer library. For dl1, go to amiga/quantizers/dl1 and run SMake. A library called "dl1" (note no ".library") should appear in amiga/library/quantizers. That is all that is needed to get a working mesa library. USING THE LIBRARY ================= To compile a program using AmigaMesaRTL, make sure the compiler can see the files in amiga/include and the link libraries in amiga/lib (by e.g. adding them to your INCLUDE: tree). Mesa.LIB contains autoopen code for the mesa.library, so you shouldn't have to worry about opening and closing it. Just don't forget to link with Mesa.LIB. Once you have set up your screen and window as per normal, call AmigaMesaRTLCreateContext() to create a new rendering context for the window. Make sure it is current by calling AmigaMesaRTLMakeCurrent(). Do lots of interesting graphics stuff. Don't forget that glFlush() has to be called (directly or indirectly) for the result to appear in the window. Before closing the window, you should destroy the context with AmigaMesaRTLDestroyContext(). See the included examples for inspiration.. Tags ---- AmigaMesaRTLCreateContext() and AmigaMesaRTLCreateContextA() understand the following tags: Tag Name : AMRTL_RGBAMode Values : TRUE | FALSE Default : TRUE Description : Use RGBA colour if TRUE, index colours if FALSE Tag Name : AMRTL_IndexMode Values : TRUE | FALSE Default : FALSE Description : Use index colours if TRUE, RGBA colour if FALSE Tag Name : AMRTL_NumColours Values : 2...256 Default : 256 Descrption : Number of colours to allocate Tag Name : AMRTL_NumColors Description : To keep our American friends happy Tag Name : AMRTL_ColourBase Values : 0...254 Default : 0 Description : Palette index of the first colour Tag Name : AMRTL_ColorBase Description : More Americana Tag Name : AMRTL_Quantizer Values : A string Default : Content of environment variable AmigaMesaRTL/Quantizer : or the value "dl1" if not set Description : Name of quantizer to use Tag Name : AMRTL_QuantizerVersion Values : Any ULONG Default : Content of env. variable AmigaMesaRTL/QuantizerVersion : or 0 if not set Description : Minimum library version of quantizer to use GLUT ==== Having a Mesa library is all fine and dandy, but most Mesa and OpenGL examples use the GL Utility Toolkit (GLUT) by Mark Kilgard. So the obvious answer is: we need a port of GLUT. Having looked at the GLUT source code, this is easier said than done. It is highly X11-centric, with a Windows port mixed in. I thought about it, but in the end I decided to do a from-scratch GLUT look-alike implementation. It can be found in amiga/src-glut. At present, most of the most-commonly used functions are implemented. No guarantee that they behave identically to the official GLUT distribution, but most of the redbook examples seem to work OK. Compiling GLUT -------------- To compile the GLUT library, go to the amiga/src-glut directory, set up the SCOPTIONS file to your liking, run SMake, and hey-presto! out comes amiga/lib/GLUT.LIB. Using GLUT ---------- when compiling a GLUT program, make sure you link with GLUT.LIB and Mesa.LIB. When run, a glut program will by default try to open a window on a public screen named Mesa. Use one of the zillion pubscreen managers available on AmiNet to set one up. GLUT Menus .......... The GLUT menus use the usual Amiga menu system. Instead of having a menu associated with a mouse button, there is a "Left Menu", "Middle Menu", and "Right Menu" menu. As the Amiga menu system only supports up to one level of sub-menus, any sub-sub-menus (and sub-sub-sub-menus and sub-sub-sub-sub-menus and ...) will be changed to a sub-menu after the parent. GLUT mouse buttons .................. As the right mouse button is tied up with menus, middle and right mouse button presses can be done by qualifying the left mouse button press with the Right-Amiga and Right-Alt keys respectively. For those of you with three-button mice, the middle button should also be recognised. GLUT termination ................ The GLUT main loop is traditionally terminated by exit()'ing the program. Amiga GLUT uses SAS/C's STI_ and STD_ mechanism to clean up on exit(). Quiting a GLUT program is usually done by pressing the ESC key. Clicking the window close button will cause Amiga GLUT to call the context's keyboard function with an ESC key code. However, some example programs never exit. Instead they expect the user to kill the program (by e.g. ^C). To handle such evil programs, Amiga GLUT has a panic drop-through. If pressing the window close button has no effect (i.e. the program is not listening to ESC key presses), a second click on the window close button will cause glutMainLoop() to return. This usually works as glutMainLoop() is often the last command in main() before it returns. But, as this is against the documented behaviour of glutMainLoop(), Bad Things may happen instead. GLUT keys ......... The GLUT special keys implemented are: the cursor keys, and functon keys F1 to F10. Idle .... A single glutMainLoop() loop will handle all the messages on the queue. If set, glutIdleFunc() will be called whenever glutMainLoop() finds no messages to handle (other than IDCMP_INTUITICKS) in a single loop. (This is in contrast to a macintosh implementation I know of which actually speeds up if you e.g. press a key). Running a GLUT program ---------------------- Any GLUT program which calls glutInit() (as all should), recognise the following command line options: Option : -numcolours Values : 2...256 Default : 248 Description : Set value for AMRTL_NumColours Option : -numcolors Description : Americana Option : -colourbase Values : 0...254 Default : 8 Description : Set value for AMRTL_ColourBase Option : -colorbase Description : Americana Option : -pubscreen Values : <any name> Default : MESA Description : Set the public screen to open windows on Option : -quantizer Values : <any name> Default : <not set> Description : Set value for AMRTL_Quantizer Option : -quantizerversion Values : <any ULONG> Default : <not set> Description : Set value for AMRTL_QuantizerVersion So for example, to get some interesting things going on the same screen without the colours interfering: run bounce -colourbase 8 -numcolors 4 run gears -colourbase 12 -numcolors 64 run isosurf -va -colourbase 76 -numcolors 88 run fog -colourbase 164 -numcolors 92 If a program doesn't appear to give any output, check to see if it calls glFlush(), or anything that calls it (like glutSwapBuffers()). If it doesn't, add it (typically at the end of the display() function). Also make sure you give the program plenty of stack. WARNING! -------- Please beware that at present, Amiga GLUT lacks a lot of error checking. Bad Things will very likely happen if Something Goes Wrong. Quantizer Plugins ================= Since version 1.1, AmigaMesaRTL has a plugin system for quantizers. They are actually just libraries. Which quantizer library to use is determined by the environment variables "AmigaMesaRTL/Quantizer" and "AmigaMesaRTL/QuantizerVersion". If they are not set, the defaults are "dl1" and "0" respectively. The AMRTL_Quantizer and AMRTL_QuantizerVersion tags, and matching glutInit() arguments, overide these. The quantizers are expected to be found in the "libs:quantizers/" directory. Writing your own quantizer -------------------------- The quantizer API is documented in amiga/quantizers/quantizer.doc and the .fd file is amiga/libraries/quantizers/quantizer.fd. See the dl1 quantizer source for an example implementation. If there is something you would like to see added to the interface, tell me. Particularly I would like to know if ARGB is more convenient than RGBA. FUTURE ====== Mesa 3.0 will shortly emerge from beta state. It shouldn't take long for me update the library to it when it does. Better colour management. At present, no locking is done, and multiple windows of the same GLUT instance will share the same palette indices. Fix the zillions of bugs everyone but me will no doubt find. Maybe an RTG option. I don't have access to a graphics board, and when P5 comes out with their PPC graphics boards, this whole library might be obsolete. Change GLUT to a run-time library.